package com.smart.community.feign.region.service;

import com.smart.community.feign.region.dto.RegionHierarchyInfo;
import com.smart.community.feign.region.fallback.RegionHierarchyFeignFallbackFactory;
import io.swagger.v3.oas.annotations.Operation;
import io.swagger.v3.oas.annotations.Parameter;
import io.swagger.v3.oas.annotations.tags.Tag;
import org.springframework.cloud.openfeign.FeignClient;
import org.springframework.web.bind.annotation.*;

import java.util.List;
import java.util.Map;

/**
 * 区域层级关系Feign接口
 * 
 * 提供房户层级向上追溯的核心功能，支持缴费系统根据房户ID快速定位物业公司
 * 业务流程：房户ID → 单元ID → 楼栋ID → 社区ID → 物业公司ID → 收款二维码
 * 
 * @author Wu.Liang
 * @version 1.0.0
 * @since 2025-01-30
 */
@Tag(name = "区域层级关系Feign接口", description = "区域层级关系相关Feign接口，支持缴费系统房户到物业公司的快速定位")
@FeignClient(
    name = "smart-community-region",
    path = "/region/feign/region-hierarchy",  // ✅ 使用模块名/feign前缀，符合Feign接口开发规范
    fallbackFactory = RegionHierarchyFeignFallbackFactory.class,
    contextId = "regionHierarchyFeign"
)
public interface IRegionHierarchyFeign {
    
    /**
     * 根据房户ID获取所属物业公司ID
     * 
     * 核心缴费接口：通过房户ID直接获取物业公司ID，用于获取收款二维码
     * 查询路径：房户 → 单元 → 楼栋 → 社区 → 物业公司
     * 
     * @param householdId 房户ID
     * @return 物业公司ID，如果查询失败或无关联返回null
     */
    @Operation(summary = "根据房户ID获取所属物业公司ID", description = "缴费系统核心接口，通过房户ID快速定位物业公司")
    @GetMapping("/feign/household/{householdId}/property-company-id")
    Long getPropertyCompanyIdByHouseholdId(@Parameter(description = "房户ID") @PathVariable("householdId") Long householdId);  // ✅ 直接返回数据，不包装Result
    
    /**
     * 根据房户ID获取完整的层级信息
     * 
     * 返回房户所属的单元、楼栋、社区、物业公司的完整ID和名称信息
     * 用于需要展示完整层级路径的业务场景
     * 
     * @param householdId 房户ID
     * @return 层级信息对象，包含各级ID和名称
     */
    @Operation(summary = "根据房户ID获取完整的层级信息", description = "获取房户完整的层级结构信息，包括各级ID和名称")
    @GetMapping("/feign/household/{householdId}/hierarchy-info")
    RegionHierarchyInfo getRegionHierarchyByHouseholdId(@Parameter(description = "房户ID") @PathVariable("householdId") Long householdId);
    
    /**
     * 批量根据房户ID获取物业公司ID
     * 
     * 用于批量缴费、批量查询等场景，提高查询效率
     * 返回房户ID与物业公司ID的映射关系
     * 
     * @param householdIds 房户ID列表
     * @return 房户ID与物业公司ID的映射关系，key为房户ID，value为物业公司ID
     */
    @Operation(summary = "批量根据房户ID获取物业公司ID", description = "批量获取房户对应的物业公司ID，提高批量业务处理效率")
    @PostMapping("/feign/households/property-company-ids")
    Map<Long, Long> getPropertyCompanyIdsByHouseholdIds(@Parameter(description = "房户ID列表") @RequestBody List<Long> householdIds);
    
    /**
     * 根据房户ID获取社区ID
     * 
     * 用于需要社区级别权限控制或社区数据统计的场景
     * 查询路径：房户 → 单元 → 楼栋 → 社区
     * 
     * @param householdId 房户ID
     * @return 社区ID，如果查询失败返回null
     */
    @Operation(summary = "根据房户ID获取社区ID", description = "获取房户所属的社区ID，用于社区级别的数据查询")
    @GetMapping("/feign/household/{householdId}/community-id")
    Long getCommunityIdByHouseholdId(@Parameter(description = "房户ID") @PathVariable("householdId") Long householdId);
    
    /**
     * 批量根据房户ID获取社区ID
     * 
     * 用于批量社区数据查询，支持跨社区的数据统计和权限控制
     * 
     * @param householdIds 房户ID列表
     * @return 房户ID与社区ID的映射关系，key为房户ID，value为社区ID
     */
    @Operation(summary = "批量根据房户ID获取社区ID", description = "批量获取房户对应的社区ID，支持批量社区数据查询")
    @PostMapping("/feign/households/community-ids")
    Map<Long, Long> getCommunityIdsByHouseholdIds(@Parameter(description = "房户ID列表") @RequestBody List<Long> householdIds);
}
